<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>RemoteExec Task</title>
<link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
</head>

<body>

<h2><a name="exec">RemoteExec</a></h2>
<h3>Description</h3>
<p>Executes a system command on the specified remote host or hosts.</p>

<h4>Parameters</h4>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">executable</td>
    <td valign="top">the command to execute without any command line
      arguments.</td>
    <td align="center">YES</td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">the directory in which the command should be executed.if it is not an absolute dir, the host's base dir will be instered before this dir. </td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">timeout</td>
    <td valign="top">Stop the command if it doesn't finish within the
      specified time (given in milliseconds).</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">failonerror</td>
    <td valign="top">Stop the buildprocess if the command exits with a
      return code signaling failure. Defaults to false.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">hostref</td>
    <td valign="top">reference a remote host.if hostref or hostsetref both not specified, the command will execute locally </td>
    <td valign="top" align="center">NO</td>
  </tr>
  <tr>
    <td valign="top">hostsetref</td>
    <td valign="top">reference remote hosts. if hostref or hostsetref both not specified, the command will execute locally </td>
    <td valign="top" align="center">NO</td>
  </tr>
  <tr>
    <td valign="top">transmit</td>
    <td valign="top">whether or not transmit the command to the remote host, default value is YES, if set to NO, just print the command in standard output. </td>
    <td align="center" valign="top">No</td>
  </tr>  
  <tr>
    <td valign="top">blocking</td>
    <td valign="top">if the process is blocking, the process will be stored in a process repository. you can use the <strong><a href="shutdownexec.html">shutdownexec</a></strong> task to shutdown the blocking </td>
    <td align="center" valign="top">No, default is <i>false</i></td>
  </tr>
  <tr>
    <td valign="top">duplicate</td>
    <td valign="top">the number of the processes. it will run the process in parallel. the number must not exceed the <strong>highwatermark</strong> the host.</td>
    <td align="center" valign="top">No, default is <i>1</i></td>
  </tr>
  <tr>
    <td valign="top">share</td>
    <td valign="top">if hostset is used in the task, <strong>share</strong>  means that the number of the processes specified by the <strong>duplicate</strong> will be shared among the hosts in the hostset. The sum of the <strong>highwatermark</strong> for the hostset must not exceed the <strong>duplicate</strong> number. If truns off, means that  we will execute <strong>duplicate</strong> number of the process on each host in the hostset.</td>
    <td align="center" valign="top">No, default is <i>false</i></td>
  </tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>arg</h4>
<p>Command line arguments should be specified as nested
<code>&lt;arg&gt;</code> elements. See <a
href="../using.html#arg">Command line arguments</a>.</p>
<h4><a name="env">env</a></h4>
<p>It is possible to specify environment variables to pass to the
system command via nested <code>&lt;env&gt;</code> elements.</p>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">key</td>
    <td valign="top">The name of the environment variable.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">value</td>
    <td valign="top">The literal value for the environment variable.</td>
    <td align="center" rowspan="3">Exactly one of these.</td>
  </tr>
  <tr>
    <td valign="top">path</td>
    <td valign="top">The value for a PATH like environment
      variable. You can use ; or : as path separators and Ant will
      convert it to the platform's local conventions.</td>
  </tr>
  <tr>
    <td valign="top">file</td>
    <td valign="top">The value for the environment variable. Will be
      replaced by the absolute filename of the file by Ant.</td>
  </tr>
</table>
<a name="redirector"><h4>Examples</h4></a>
<blockquote>
  <pre>  &lt;remoteexec executable=&quot;ping&quot; host=&quot;greatwall&quot;&gt;<br>     &lt;arg line=&quot;localhost -n 3&quot;/&gt;<br>     &lt;expect stream=&quot;out&quot;&gt;127.0.0.1&lt;/expect&gt;<br>  &lt;/remoteexec&gt;</pre>
</blockquote>
<p>To execute the ping command on <strong>greatwall</strong> with the specified arguments, also check the standard ouputs.</p>
<blockquote>

    <pre>&lt;remoteexec executable=&quot;ping&quot; host=&quot;greatwall&quot; duplicate=&quot;2&quot;&gt;<br>     &lt;arg line=&quot;localhost -n 3&quot;/&gt;<br>     &lt;expect stream=&quot;out&quot;&gt;127.0.0.1&lt;/expect&gt;<br>  &lt;/remoteexec&gt;</pre>
</blockquote>

<p>To launch two of  the same command on <strong>greatwall</strong> in parallel. This task will fail, because the <strong>greatwall</strong> 's duplicate number is set to the default value which is only one process is allowed to be exeucted on the host.</p>
<p>To fullfil the task, you should increase the <strong>dupliate</strong> number for the <strong>greatwall</strong> or exeucte on the host that support the requied number of processes.</p>
<h3>How to use the HostSet in executable tasks </h3>
<blockquote>
  <pre> &lt;host id=&quot;taibei&quot;   ... highwatermark=&quot;5&quot;/&gt;
 &lt;host id=&quot;hongkong&quot; ... highwatermark=&quot;5&quot;/&gt;
 &lt;host id=&quot;macau&quot;    ... highwatermark=&quot;5&quot;/&gt;

 &lt;hostset id=&quot;loaders&quot;&gt;
   &lt;host refid=&quot;taibei&quot;/&gt;
   &lt;host refid=&quot;hongkong&quot;/&gt;
   &lt;host refid=&quot;macau&quot;/&gt;
 &lt;/hostset&gt;

  &lt;remoteexec executable=&quot;ping&quot; hostset=&quot;loaders&quot; duplicate=&quot;3&quot;&gt;<br>     &lt;arg line=&quot;localhost -n 3&quot;/&gt;<br>     &lt;expect stream=&quot;out&quot;&gt;127.0.0.1&lt;/expect&gt;<br>  &lt;/remoteexec&gt;</pre>
</blockquote>
<p>To run two of the ping command on hostset <strong>loaders</strong> in parallel, which involved three host, <strong>taibei</strong> and <strong>hongkong</strong> and <strong>macau</strong>.</p>
<h3>How to use attribute share </h3>
<blockquote>
  <pre>  &lt;remoteexec executable=&quot;ping&quot; hostset=&quot;loaders&quot; duplicate=&quot;12&quot; <strong>share</strong>=&quot;yes&quot;&gt;<br>     &lt;arg line=&quot;localhost -n 3&quot;/&gt;<br>     &lt;expect stream=&quot;out&quot;&gt;127.0.0.1&lt;/expect&gt;<br>  &lt;/remoteexec&gt;</pre>
</blockquote>
<p>To run total number 12 processes of the ping command on <strong>loaders</strong> hostset. The share results could be 5 processes on <strong>macau</strong>, 5 processes on <strong>hongkong</strong>, and 2 process on <strong>taibei</strong>. The total <strong>highwatemark</strong> of the <strong>loaders</strong> hostset is 5+5+5=15, so the <strong>duplicate</strong> number of the task must not be exceed 15. </p>

<p><b>Note:</b> Although it may work for you to specify arguments using
a simple arg-element and separate them by spaces it may fail if you switch to
a newer version of the JDK. JDK &lt; 1.2 will pass these as separate arguments
to the program you are calling, JDK &gt;= 1.2 will pass them as a single
argument and cause most calls to fail.</p>
<p><b>Note2:</b> If you are using Ant on Windows and a new DOS-Window pops up
for every command which is executed this may be a problem of the JDK you are using.
This problem may occur with all JDK's &lt; 1.2.</p>
<p>
<b>Timeouts: </b> If a timeout is specified, when it is reached the
sub process is killed and a message printed to the log. The return
value of the execution will be "-1", which will halt the build if
<tt>failonerror=true</tt>, but be ignored otherwise.

<hr>
<p align="center">Copyright &copy; 2005 Dant Organization. All rights Reserved.</p>

</body>
</html>

